---
type: integration
title: '@astrojs/vercel'
description: 学习如何使用 @astrojs/vercel 适配器来部署你的 Astro 项目。
sidebar:
  label: Vercel
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/vercel/'
category: adapter
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Since from '~/components/Since.astro';
import ReadMore from '~/components/ReadMore.astro'
import { Steps } from '@astrojs/starlight/components';

此适配器允许 Astro 将你的 [按需渲染路由及其功能](/zh-cn/guides/on-demand-rendering/) 部署到 [Vercel](https://www.vercel.com/)，包括 [服务器群岛](/zh-cn/guides/server-islands/)，[actions](/zh-cn/guides/actions/) 以及 [sessions](/zh-cn/guides/sessions/)。

如果你使用 Astro 作为静态站点生成器，只有当你使用额外的 Vercel 服务时（例如 [Vercel 网络分析](https://vercel.com/docs/analytics)，[Vercel 图像优化](https://vercel.com/docs/image-optimization)），你才需要这个适配器。否则，你不需要适配器来部署你的静态站点。

在我们的 [Vercel 部署指南](/zh-cn/guides/deploy/vercel/) 中学习和部署你的 Astro 站点。

## 为什么选择 Astro Vercel？

[Vercel](https://www.vercel.com/) 是一个部署平台，它允许你通过直接连接到 GitHub 仓库来托管你的站点。这个适配器增强了 Astro 的构建过程，为通过 Vercel 进行部署做好了准备。

## 安装

Astro 包含了一个 `astro add` 命令，用于自动设置官方集成。如果你愿意，也可以[手动安装集成](#手动安装)。

在 Astro 项目中使用以下 `asrto add` 命令添加 Vercel 适配器，以启用按需渲染。这将安装 `@astrojs/vercel` 并一步到位地对你的 `astro.config.mjs` 文件进行相应的更改。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add vercel
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add vercel
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add vercel
  ```
  </Fragment>
</PackageManagerTabs>

现在，你可以启用 [对每个页面的按需渲染](/zh-cn/guides/on-demand-rendering/#启用按需渲染)，或者将你的构建输出配置设置为 `output: 'server'` 从而 [默认对所有页面都进行服务器端渲染](/zh-cn/guides/on-demand-rendering/#server-模式)。

### 手动安装

首先，使用适合你的包管理器，将 `@astrojs/vercel` 适配器添加到你项目的依赖项中：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/vercel
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/vercel
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/vercel
  ```
  </Fragment>
</PackageManagerTabs>

然后，将适配器添加到 `astro.config.*` 文件中：

```js title="astro.config.mjs" ins={2, 6}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel(),
});
```

## 用法

<ReadMore>了解更多关于 [将项目部署到 Vercel](/zh-cn/guides/deploy/vercel/) 的信息。</ReadMore>

你可以通过 CLI ( `vercel deploy` ) 或者通过 [Vercel 控制台](https://vercel.com/) 连接到你的新仓库进行部署。或者，你可以在本地创建生产版本构建：

```sh
astro build
vercel deploy --prebuilt
```

## 配置

要配置这个适配器，将一个对象传递给 `astro.config.mjs` 中的 `vercel()` 函数调用：

### `webAnalytics`
<p>

**类型：** `VercelWebAnalyticsConfig`<br/>
**适用于：** Serverless, Static<br/>
<Since v="3.8.0" pkg="@astrojs/vercel" />
</p>

对于 `@vercel/analytics@1.3.x` 或更早的版本时，你可以在 Astro 配置中设置 `webAnalytics： { enabled： true }` 以将 Vercel 的跟踪脚本注入到你所有的页面中。

对于 `@vercel/analytics@1.4.0` 及更高版本，请使用 Vercel 的 Analytics 组件来启用 [Vercel Web Analytics](https://vercel.com/docs/concepts/analytics)。

```js title="astro.config.mjs" ins={7-9}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    webAnalytics: {
      enabled: true,
    },
  }),
});
```

### `imagesConfig`

<p>

**类型：** `VercelImageConfig`<br/>
**适用于：** Serverless, Static<br/>
<Since v="3.3.0" pkg="@astrojs/vercel" />
</p>

[Vercel 的图片优化 API](https://vercel.com/docs/concepts/image-optimization) 选项。查看 [Vercel 的图片优化配置文档](https://vercel.com/docs/build-output-api/v3/configuration#images)以获取支持的参数的完整列表。

`domains` 和 `remotePatterns` 属性将自动使用 [Astro 对应的 `image` 设置](/zh-cn/reference/configuration-reference/#image-选项) 来填充。

```js title="astro.config.mjs" ins={8-10}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imagesConfig: {
      sizes: [320, 640, 1280],
    },
  }),
});
```

### `imageService`

<p>

**类型：** `boolean`<br/>
**适用于：** Serverless, Static<br/>
<Since v="3.3.0" pkg="@astrojs/vercel" />
</p>

启用后，在生产中会自动配置并使用由 Vercel Image Optimization API 提供支持的[图像服务](/zh-cn/reference/image-service-reference/) 。在开发中，将使用由 [`devImageService`](#devimageservice) 指定的图像服务。

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/static';

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imageService: true,
  }),
});
```

```astro title="src/pages/index.astro"
---
import { Image } from 'astro:assets';
import astroLogo from '../assets/logo.png';
---

<!-- 这里的组件 -->
<Image src={astroLogo} alt="My super logo!" />

<!-- 将会被编译成如下 HTML -->
<img
  src="/_vercel/image?url=_astro/logo.hash.png&w=...&q=..."
  alt="My super logo!"
  loading="lazy"
  decoding="async"
  width="..."
  height="..."
/>
```

### `devImageService`

<p>

**类型：** `'sharp' | string`<br/>
**默认值：** `sharp`<br />
**适用于：** Serverless, Static<br />
<Since v="3.8.0" pkg="@astrojs/vercel" />
</p>

当 [imageService](#imageservice) 启用时，允许你在开发中配置使用哪个图像服务。如果你无法在开发机器上安装 Sharp 的依赖项，但使用另一个图像服务（如 Squoosh）可以让你在开发环境中预览图像，这可能很有用。但构建不会受其影响，将始终使用 Vercel 的图像优化。

它也可以设置为任意值，以使用自定义图像服务而不是 Astro 的内置图像服务。

```js title="astro.config.mjs" ins={7-8}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    imageService: true,
    devImageService: 'sharp',
  }),
});
```

### `isr`

<p>

**类型：** <code>boolean |   VercelISRConfig</code><br/>
**默认值：** `false`<br/>
**适用于：** Serverless<br/>
<Since v="7.2.0" pkg="@astrojs/vercel" />
</p>

允许你的项目作为一个 [ISR (增量式静态再生)](https://vercel.com/docs/incremental-static-regeneration) 功能部署，这个功能以首次请求后预渲染页面相同的方式缓存你按需渲染的页面。

要启用此功能，在你的 `astro.config.mjs` 中的 Vercel 适配器配置里将 `isr` 设置为 true：

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    isr: true,
  }),
});
```

请注意，ISR 功能请求不包括搜索参数，这与静态模式下的 [请求](/zh-cn/reference/api-reference/#request) 类似。

#### ISR 缓存失效

默认情况下，ISR 函数会在你的部署期间进行缓存。你可以通过设置过期时间，或者完全排除特定路由不进行缓存，来进一步控制缓存。

##### 基于时间的失效

你可以通过配置秒为单位的 `expiration` 值来改变缓存路由的时间长度：

```js title="astro.config.mjs" {7-10}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    isr: {
      // 在首次请求时缓存所有页面，并保存 1 天
      expiration: 60 * 60 * 24,
    },
  }),
});
```

##### 从缓存中排除路径

要实现 Vercel 的[草稿模式](https://vercel.com/docs/build-output-api/v3/features#draft-mode)或[按需增量式静态再生 (ISR)](https://vercel.com/docs/build-output-api/v3/features#on-demand-incremental-static-regeneration-isr)，你可以创建一个绕过令牌，并将其连同任何要从缓存中排除的路由一起提供给 `isr` 配置：

```js title="astro.config.mjs" {6-15}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
    adapter: vercel({
        isr: {
            // 你创建的一个私密随机字符串。
            bypassToken: "005556d774a8",
            // 总是提供最新内容的路径。
            exclude: [
              '/preview', 
              '/auth/[page]',
              /^\/api\/.+/ // 自 @astrojs/vercel @v8.1.0 以来支持的正则表达式
            ]
        }
    })
})
```

### `includeFiles`

<p>

**类型：** `string[]`<br/>
**适用于：** Serverless
</p>

使用此属性来强制将文件与你的函数打包在一起。当你发现缺失文件时，这很有帮助。

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    includeFiles: ['./my-data.json'],
  }),
});
```

<p>

### `excludeFiles`
</p>

**类型：** `string[]`<br/>
**适用于：** Serverless

使用此属性来从打包过程中排除任何会被包含的文件。

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    excludeFiles: ['./src/some_big_file.jpg'],
  }),
});
```

### `maxDuration`

<p>

**类型：** `number`<br/>
**适用于：** Serverless
</p>

使用这个属性来延长或限制无服务器函数运行的最长持续时间（以秒为单位），直到超时。请参阅 [Vercel 文档](https://vercel.com/docs/functions/serverless-functions/runtimes#maxduration) 获取你的账号计划的默认和最大时限。

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
// ...
  adapter: vercel({
    maxDuration: 60
  }),
});
```

### `skewProtection`

<p>

**类型：** `boolean`<br/>
**适用于：** Serverless
<Since pkg="@astrojs/vercel" v="7.6.0" />
</p>
使用此属性启用 [Vercel Skew protection](https://vercel.com/docs/deployments/skew-protection)（适用于 Vercel Pro 和企业账户）。

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
// ...
  adapter: vercel({
    skewProtection: true
  }),
});
```

### 在 Vercel Edge 函数上运行 Astro 中间件

`@astrojs/vercel` 适配器可以根据你代码库中的 Astro 中间件创建一个 [边缘函数](https://vercel.com/docs/functions/edge-functions)。当启用 `edgeMiddleware` 时，边缘函数将为包括静态资源、预渲染页面和按需渲染页面在内的所有请求执行你的中间件代码。

对于按需渲染的页面，`context.locals` 对象会被 JSON 序列化并通过标头发送给无服务器函数，由该函数执行渲染。作为安全措施，除非请求来自生成的边缘函数，否则无服务器函数将拒绝服务，并返回 `403 Forbidden` 响应。

这是一个选择性功能。要启用它，请将 `edgeMiddleware` 设置为 `true`：

```js title="astro.config.mjs" "edgeMiddleware: true"
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    edgeMiddleware: true,
  }),
});
```
边缘中间件可以用 `ctx.locals.vercel.edge` 访问 Vercel 的 [`RequestContext`](https://vercel.com/docs/functions/edge-middleware/middleware-api#requestcontext) 。如果你正在使用 TypeScript，可以通过更新 `src/env.d.ts` 来使用 `EdgeLocals` [获得正确的类型定义](/zh-cn/guides/typescript/#扩展全局类型)：

```ts
type EdgeLocals = import('@astrojs/vercel').EdgeLocals

declare namespace App {
  interface Locals extends EdgeLocals {
    // ...
  }
}
```

### Sessions

Astro [Session API](/zh-cn/guides/sessions/) 允许你在请求间，轻松地存储用户数据。该功能可用于用户数据和偏好选项，购物车内容，资格鉴权。不同于 cookie 存储，这里不存在对数据大小的限制，并且可以将其存储在不同的设备上。

当你在 Vercel 上使用会话时，你需要为会话（session）存储 [配置驱动](/zh-cn/reference/configuration-reference/#sessiondriver)。你可以从 [Vercel 插件市场](https://vercel.com/marketplace?category=storage) 中安装一个存储集成。

例如，如果你已经安装了 [Redis 集成](https://vercel.com/marketplace?category=storage&search=redis) 并将你的网站连接到了数据库：

<Steps>

1. 安装 `ioredis` 包：

   <PackageManagerTabs>
     <Fragment slot="npm">
     ```sh
     npm install ioredis
     ```
     </Fragment>
     <Fragment slot="pnpm">
     ```sh
     pnpm install ioredis
     ```
     </Fragment>
     <Fragment slot="yarn">
     ```sh
     yarn add ioredis
     ```
     </Fragment>
   </PackageManagerTabs>

2. 使用 [Vercel CLI](https://vercel.com/docs/cli) 来加载你的环境变量：

    ```sh
    vercel env pull .env.local
    ```
    这一步将会在你的项目根目录下创建一个 `.env.local` 文件，并会在进行本地开发时，提供连接到 Redis 数据库所需的环境变量。

3. 配置会话驱动：

    ```js title="astro.config.mjs" ins={6-11}
    import { defineConfig } from 'astro/config';
    import vercel from '@astrojs/vercel';

    export default defineConfig({
      adapter: vercel(),
      session: {
        driver: 'redis',
        options: {
          url: process.env.REDIS_URL,
        },
      },
    });
    ```

</Steps>

## Node.js 版本支持

`@astrojs/vercel` 适配器支持特定的 Node.js 版本，用于在 Vercel 上部署 Astro 项目。要在 Vercel 上查看受支持的 Node.js 版本，请单击项目的设置选项卡，然后向下滚动到 “Node.js版本” 部分。

查看 [Vercel 文档](https://vercel.com/docs/functions/serverless-functions/runtimes/node-js#default-and-available-versions) 了解更多信息。

## 实验性功能

以下功能当前可用，但在未来更新中可能会发生破坏性变更。如果你在项目中使用这些功能，请密切关注 [`@astrojs/vercel` CHANGELOG](https://github.com/withastro/astro/tree/main/packages/integrations/vercel/CHANGELOG.md) 以获取最新动态。

### `experimentalStaticHeaders`

<p>
**类型：** `boolean`<br/>
**默认值：** `false`<br />
**可用于：** Serverless <br/>
<Since pkg="@astrojs/vercel" v="8.2.0" />
</p>

启用在 Vercel 配置中为预渲染页面指定自定义标头。

启用后，当 Astro 功能（如内容安全策略）提供静态标头时，适配器会将其 [保存在 Vercel 的 `vercel.json` 文件中](https://vercel.com/docs/project-configuration#headers)。

例如，当启用 [实验性的内容安全策略](/zh-cn/reference/experimental-flags/csp/) 时，可以使用 `experimentalStaticHeaders` 将 CSP `headers` 添加到你的 Vercel 配置中，而不是创建 `<meta>` 元素：

```js title="astro.config.mjs" {9}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  experimental: {
    csp: true
  },
  adapter: vercel({
    experimentalStaticHeaders: true 
  })
});
```


[astro-integration]: /zh-cn/guides/integrations-guide/
